#!/usr/bin/env python3
# -*- coding: utf-8 -*-

r"""Useful functions needed in the process of learning NumPy, Pandas, Matplotlib.

Functions:
+ arr_info()
+ arr_stat()

"""

# 特殊属性
__author__ = "Acrylic Studio"
__all__ = ["arr_info", "arr_stat"]

# 模块导入
import numpy


def mod_acti() -> None:
    """【函数】测试模块是否导入"""
    print("[Import Successfully] Module is activated, your functions are ready to use. <EOF>")
    return None


def arr_info(*FP_array_list: list) -> None:
    """【函数】显示ndarray的基本信息
    
    参数：
    + FP_array_list: [列表] 包含数组名称的列表。
    """
    i = 0
    for FP_array in FP_array_list:
        i += 1
        print("【%d】" %i)
        if (isinstance(FP_array, numpy.ndarray)):
            if (FP_array.ndim != 0):
                __print_info_ndarray(FP_array)
            elif (FP_array.ndim == 0):
                print(" 数组元素（Element）:", FP_array)
        else:   # 非ndarray对象调用 ndim 等信息时会报错，故其他类型的需要单独显示
            print(" 类 型:", type(FP_array))
            print(FP_array)
    return None


def __print_info_ndarray(FP_array: list) -> None:
    """【函数】打印ndarray的基本信息
    """
    print(" 多维数组（ndarray）:\n", FP_array)
    print(" 数组维数（ndim）:", FP_array.ndim)       # Number of Array Dimension（一维数组、二维数组等）
    print(" 维度元组（shape）:", FP_array.shape)     # Tuple of Array Dimension（类似矩阵的m行n列）
    print(" 数据类型（dtype）:", FP_array.dtype)     # Data-type of Array's Elements
    return None


def arr_stat(FP_array) -> None:
    """【函数】显示ndarray的统计信息
    
    参数：
    + FP_array: [Iterable] Numpy 中的 ndarray 对象，或 list、tuple 等其他可迭代对象；
    """
    print("【统计信息】")
    if (len(FP_array) == 1):
        print("【Warning】该数组只有一个元素，可能无法有效统计。\n 数组元素:", FP_array)    # 后续考虑用 except 语句优化该警告
        __print_statistics_ndarray(FP_array, set_ddof=0)
    else:
        __print_statistics_ndarray(FP_array)
    return None


def __print_statistics_ndarray(FP_array, set_ddof=1) -> None:
    """【函数】打印ndarray的基本信息
    """
    print(" 样本均值（mean）: %.4f" %numpy.mean(FP_array))
    print(" 样本标准差（std）: %.4f" %numpy.std(FP_array))
    print(" 修正样本标准差: %.4f" %numpy.std(FP_array, ddof=set_ddof))
    print(" 样本方差（var）: %.4f" %numpy.var(FP_array))
    print(" 修正样本方差: %.4f" %numpy.var(FP_array, ddof=set_ddof))
    print(" 最大值（max）:", numpy.max(FP_array), "\t索引（index）:",numpy.argmax(FP_array))
    print(" 最小值（max）:", numpy.min(FP_array), "\t索引（index）:",numpy.argmin(FP_array))
    return None


if (__name__ == "__main__"):
    array = numpy.arange(1,13).reshape(3,4)
    arr_info([array])
    arr_stat(array)

    arr_2 = numpy.array([1])
    arr_stat(arr_2)
